What is vfile?
The vfile npm package is a virtual file format for text processing systems, which allows for the manipulation and handling of file-related information in a structured and consistent way. It is commonly used in projects involving the processing of markdown, text, and similar content, providing a standardized interface for plugins and utilities.
What are vfile's main functionalities?
Creating and modifying virtual files
This feature allows users to create a new virtual file and modify its contents. The example demonstrates creating a vfile with initial content and then appending additional text to it.
const vfile = require('vfile');
const file = vfile({path: './example.txt', contents: 'Hello, world!'});
file.contents += ' Modified content.';
console.log(file.contents);
Accessing file metadata
This feature enables users to access metadata of the file such as the path and basename. The example shows how to create a vfile and retrieve its path and basename properties.
const vfile = require('vfile');
const file = vfile({path: './example.txt', contents: 'Hello, world!'});
console.log(file.path); // Outputs: './example.txt'
console.log(file.basename); // Outputs: 'example.txt'
Handling errors and messages
This feature is useful for adding error or warning messages to a file, which can be particularly helpful in linting tools or compilers. The example demonstrates adding an error message to a vfile and logging all associated messages.
const vfile = require('vfile');
const file = vfile();
file.message('Unknown error', {line: 1, column: 1});
console.log(file.messages);
Other packages similar to vfile
vinyl
Vinyl is a virtual file format that is often used in the gulp build system. It is similar to vfile in that it represents file objects in a virtual form, but it is more focused on being used with streams, particularly in the context of gulp's pipelines.
mem-fs
mem-fs provides an in-memory file system which stores file representations similar to vfile. While vfile is designed for text processing with a focus on linting and transformation, mem-fs is geared more towards temporary storage and manipulation of files in memory during tasks like scaffolding or testing.
VFile is a virtual file format used by unified,
a text processing umbrella (it powers retext for
natural language, remark for markdown, and
rehype for HTML). Each processors that parse, transform,
and compile text, and need a virtual representation of files and a
place to store messages about them. Plus, they work in the browser.
VFile provides these requirements at a small size, in IE 9 and up.
VFile is different from the excellent vinyl
in that it has a smaller API, a smaller size, and focuses on
messages.
VFile can be used anywhere where files need a lightweight representation.
For example, it’s used in:
documentation
— The documentation system for modern JavaScriptweh
— Declarative small site generatorgeojsonhint
— Complete, fast, standards-based validation for geojson
Installation
npm:
npm install vfile
Table of Contents
Usage
var vfile = require('vfile');
var file = vfile({path: '~/example.txt', contents: 'Alpha *braavo* charlie.'});
file.path;
file.dirname;
file.extname = '.md';
file.basename;
file.basename = 'index.text';
file.history;
file.message('`braavo` is misspelt; did you mean `bravo`?', {line: 1, column: 8});
console.log(file.messages);
Yields:
[ { [~/index.text:1:8: `braavo` is misspelt; did you mean `bravo`?]
message: '`braavo` is misspelt; did you mean `bravo`?',
name: '~/index.text:1:8',
file: '~/index.text',
reason: '`braavo` is misspelt; did you mean `bravo`?',
line: 1,
column: 8,
location: { start: [Object], end: [Object] },
ruleId: null,
source: null,
fatal: false } ]
Utilities
The following list of projects includes tools for working with virtual
files. See Unist for projects working with nodes.
Reporters
The following list of projects show linting results for given virtual files.
Reporters must accept Array.<VFile>
as their first argument, and return
string
. Reporters may accept other values too, in which case it’s suggested
to stick to vfile-reporter
s interface.
API
VFile([options])
Create a new virtual file. If options
is string
or Buffer
, treats
it as {contents: options}
. If options
is a VFile
, returns it.
All other options are set on the newly created vfile
.
Path related properties are set in the following order (least specific
to most specific): history
, path
, basename
, stem
, extname
,
dirname
.
It’s not possible to set either dirname
or extname
without setting
either history
, path
, basename
, or stem
as well.
Example
vfile();
vfile('console.log("alpha");');
vfile(Buffer.from('exit 1'));
vfile({path: path.join(__dirname, 'readme.md')});
vfile({stem: 'readme', extname: '.md', dirname: __dirname});
vfile({other: 'properties', are: 'copied', ov: {e: 'r'}});
vfile.contents
Buffer
, string
, null
— Raw value.
vfile.cwd
string
— Base of path
. Defaults to process.cwd()
.
vfile.path
string?
— Path of vfile
. Cannot be nullified.
vfile.basename
string?
— Current name (including extension) of vfile
. Cannot
contain path separators. Cannot be nullified either (use
file.path = file.dirname
instead).
vfile.stem
string?
— Name (without extension) of vfile
. Cannot be nullified,
and cannot contain path separators.
vfile.extname
string?
— Extension (with dot) of vfile
. Cannot be set if
there’s no path
yet and cannot contain path separators.
vfile.dirname
string?
— Path to parent directory of vfile
. Cannot be set if
there’s no path
yet.
vfile.history
Array.<string>
— List of file-paths the file moved between.
vfile.messages
Array.<VMessage>
— List of messages associated with the file.
vfile.data
Object
— Place to store custom information. It’s OK to store custom
data directly on the vfile
, moving it to data
gives a little more
privacy.
VFile#toString([encoding])
Convert contents of vfile
to string. If contents
is a buffer,
encoding
is used to stringify buffers (default: 'utf8'
).
VFile#message(reason[, position][, origin])
Associates a message with the file, where fatal
is set to false
.
Constructs a new VMessage
and adds it to
vfile.messages
.
Returns
VMessage
.
VFile#info(reason[, position][, origin])
Associates an informational message with the file, where fatal
is set to
null
. Calls #message()
internally.
Returns
VMessage
.
VFile#fail(reason[, position][, origin])
Associates a fatal message with the file, then immediately throws it.
Note: fatal errors mean a file is no longer processable.
Calls #message()
internally.
Throws
VMessage
.
License
MIT © Titus Wormer